ODFacet

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODFacet

Superclasses
ODObject
Subclasses
none

An object of the ODFacet class holds nonpersistent information about the layout of parts and describes the location of a frame on a particular canvas for display and event dispatching.

Description
A facet object represents a visible, drawable frame or portion of a frame. In the simplest case, each embedded frame in a document is displayed and manipulated using a single facet. In some cases, however, your part might need to display portions of the same embedded frame in several places, such as in a split view. In that case, one or more facets might manage the layout of one frame. All facets of a frame might display that frame's content identically, or a part might store user-defined part info data in the facet to distinguish among its different facets. The part info might also consist of graphics-system-specific information used for displaying the facet, such as a QuickDraw GX view port.
Facets are organized hierarchically. Each window or printed page has a single facet, the root facet, which is the topmost facet visible in the document window. All other facets contained in that window descend from the root facet. Each facet of a given frame is contained within a facet of that frame's containing frame.
Your part creates a facet object for each visible embedded frame by calling its own display facet's CreateEmbeddedFacet method (page 238). Your part can also create a root facet (for printing) by calling the window-state object's CreateFacet method (page 857). These methods return a reference to a facet object.
Facets may or may not exist for frames that have been previously visible and that have scrolled out of view, and parts may or may not create facets for frames that are expected to be visible soon. The only requirement is that facets must exist for all currently visible frames. A visible facet always has a frame, and that frame is defined for the lifetime of the facet; once set, it cannot be changed. Facets that are not currently visible in a window may be purged from memory under low-memory conditions.

Facet Geometry
Facets hold information regarding the geometry of their corresponding frames. Each facet maintains an active shape, a clip shape, and an external transform. The clip shape and external transform must always be valid.

The active shape defines the area within a frame in which the facet's embedded part is willing to receive geometry-based user events, such as mouse clicks. It is commonly identical to the frame shape of the facet's frame, but it might be modified to coincide with the used shape or some other shape. The facet's embedded part controls the active shape.
The clip shape defines the area within a frame in which drawing can occur; it is the area unobscured by overlapping content of the containing part. If it is unobscured, the clip shape is identical to the frame shape of the facet's frame. The facet's containing part controls the clip shape.
The external transform describes the transform that is applied to a facet to position, scale, or otherwise transform the image drawn within the facet in the coordinate space of its containing part. The facet's containing part controls the external transform.

Facets and Canvases
A facet might possess its own canvas. If a particular facet in a window's facet hierarchy has an attached canvas, it and all its embedded facets (and their embedded facets, and so on) draw to that canvas. Each facet inherits its canvas from its containing facet; the inherited canvas is called the parent canvas. For most drawing, only a window's root facet needs a canvas. For offscreen double-buffering or image manipulation, however, a part can create a canvas and attach it to an embedded facet, copying the image of the offscreen canvas to its parent canvas during updates.
Because a facet can simultaneously have both a window canvas and an offscreen canvas, there can be two drawing environments to consider. The aggregate clip shape, content transform, and frame transform position and clip the facet on the closest drawing environment (the closest canvas in the facet hierarchy, which may or may not be the window canvas). During real-time interactions such as rubber-banding or dragging, your part might need to display directly in the window. In such cases, the window aggregate clip shape, window content transform, and window frame transform specifically position and clip the facet on the window canvas.
The ODFacet class includes several methods that specify geometry (shape and transform objects) or calculate positions on a canvas. Because these calculations necessarily assume a coordinate system, the ODFacet methods include a parameter, biasCanvas, that allows you to specify a canvas to whose coordinate space the geometry is biased. The bias canvas uses a bias transform to convert from the coordinate system used for drawing on the canvas to the coordinate system (platform-normal coordinates) used by the current graphics system. For more information related to bias transforms, see the ODCanvas class description (page 62).

Methods
This section presents summary descriptions of the ODFacet methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Creating Objects

CreateEmbeddedFacet

Creates a facet for the specified frame embedded in this facet.
CreateFacetIterator

Creates a facet iterator object for the embedded facets of this facet.
CreateCanvas
Creates a canvas object.
CreateShape
Creates a shape object.
CreateTransform
Creates a transform object.
Facet Hierarchy

GetContainingFacet
Returns a reference to the containing facet of this facet.
GetFrame
Returns a reference to this facet's frame.
GetWindow
Returns a reference to the window this facet is displayed in.
RemoveFacet
Removes an embedded facet from this facet.
MoveBefore
Repositions an embedded facet of this facet in front of a sibling facet.
MoveBehind
Repositions an embedded facet of this facet behind a sibling facet.
Facet Geometry

AcquireActiveShape
Returns a reference to the active shape for this facet.
ChangeActiveShape
Assigns the specified shape as the active shape of this facet.
AcquireClipShape
Returns a reference to this facet's clip shape.
ChangeGeometry
Assigns the specified clip shape, external transform, or both to this facet.
AcquireExternalTransform

Returns a reference to this facet's external transform.
Facet-Canvas Geometry

GetCanvas
Returns a reference to the canvas associated with this facet.
ChangeCanvas
Attaches a canvas to this facet.
HasCanvas
Returns a Boolean value that indicates whether this facet has its own canvas.
AcquireAggregateClipShape

Calculates and returns a reference to a shape object that represents the aggregate clip shape of this facet.
AcquireContentTransform

Calculates and returns a reference to a transform object that represents the content transform of this facet.
AcquireFrameTransform

Calculates and returns a reference to a transform object that represents the frame transform of this facet.
Window-Canvas Geometry

AcquireWindowAggregateClipShape

Calculates and returns a reference to a shape object that represents the window aggregate clip shape of this facet.
AcquireWindowContentTransform

Calculates and returns a reference to a transform object that represents the window-content transform of this facet.
AcquireWindowFrameTransform
Calculates and returns a reference to a transform object that represents the window-frame transform of this facet.
Point Testing

ContainsPoint
Returns a Boolean value that indicates whether the specified point is within the area of this facet.
ActiveBorderContainsPoint
Returns a Boolean value that indicates whether this facet's frame is active and a point is within its active frame border.
Imaging

IsSelected
Returns a Boolean value that indicates whether this facet is selected within its containing part.
SetSelected
Specifies whether this facet is currently being selected within its containing part.
GetHighlight
Returns the highlight state for this facet.
ChangeHighlight
Changes the highlight state for this facet.
Draw
Tells this facet's part to draw itself within the specified portion of this facet.
DrawActiveBorder
Updates the active frame border for this facet.
DrawChildren
Draws all embedded facets of this facet that need updating.
DrawChildrenAlways
Draws all embedded facets of this facet, whether they need updating or not.
DrawnIn
Called when this facet has been drawn in without an update event being generated.
Invalidate
Marks the specified area in this facet as in need of updating.
InvalidateActiveBorder

Marks the active frame border of this facet as in need of updating.
Validate
Marks the specified area in this facet as no longer in need of updating.
Update
Updates this facet's canvas by drawing this facet and any of its embedded facets whose clip shape intersects the specified area of the canvas.
Part Info

GetPartInfo
Returns the part info data for this facet.
SetPartInfo
Assigns part info data to this facet.

Methods
AcquireActiveShape
AcquireAggregateClipShape
AcquireClipShape
AcquireContentTransform
AcquireExternalTransform
AcquireFrameTransform
AcquireWindowAggregateClipShape
AcquireWindowContentTransform
AcquireWindowFrameTransform
ActiveBorderContainsPoint
ChangeActiveShape
ChangeCanvas
ChangeGeometry
ChangeHighlight
ContainsPoint
CreateCanvas
CreateEmbeddedFacet
CreateFacetIterator
CreateShape
CreateTransform
Draw
DrawActiveBorder
DrawChildren
DrawChildrenAlways
DrawnIn
GetCanvas
GetContainingFacet
GetFrame
GetHighlight
GetPartInfo
GetWindow
HasCanvas
Invalidate
InvalidateActiveBorder
IsSelected
MoveBefore
MoveBehind
RemoveFacet
SetPartInfo
SetSelected
Update
Validate